The World of Computer Software/The World of Computer Software.iso/grphme10.zip/GRAPHME.DOC

Text File | 1992-12-08 | 23KB | 521 lines

                    ┌─────────────────────┐
                    │  G R A P H - M E !  │
                    │    by Tom Dibble,   │
                    │  the tomster of wpi │
                    └─────────────────────┘

THE PROGRAM:
     Graph-Me! is a basic two- and three- dimensional graphing
     utility.  Supported are rectangular, "box" (3-d cartesian),
     polar, cylindrical, and spherical coordinate systems.  A
     full compliment of mathematical operations is also
     available, ranging from the basics (+, -, ...) to the more
     powerful (sin, asin ... ) and even to the obscure (modulus,
     acsc ...).  All operations are supported in all modes.

FEATURES:
     Full editing of all input values.
     Visual interface for most operations, such as rotations,
     zooms, and shifts.
     Text-based point-and-click interface for major operations.

REGISTRATION:
     This program, Graph-Me!, is shareware.  This means that you
     may use it as an evaluation copy for a few weeks before
     actually purchasing it.  The evaluation time-period expires
     four weeks (one month) after Graph-Me! is first used on a
     computer.  Registration entitles you to by-mail (or email)
     notification of each update of the program, and lasts
     through the entirety of the next major revision.  This means
     that if you register version 1.0, you will automatically be
     registered for version 1.1, 1.2 ... 2.0 ... 2.9 when they
     come out.  You will need to re-register for version 3.0.
     Most of all, however, registering gives you tremendous peace
     of mind, and the freedom of knowing you don't have to hide
     from the Software Piracy Police for the rest of your natural
     lifetime ...

     The price is set at $15 per user.  The registered copy may
     be used on more than one computer at once as long as only
     one person is using it at any one time, much like a book in
     the library.

     Why so cheap?  Because I do not intend to make much money on
     (this version of) this program.  Instead, I would just like
     to see how wide-spread its use becomes.  Future registration
     fees MAY INCREASE! so register your copy now!  (Actually,
     they probably won't, unless further improvements to the
     program significantly increase the amount of time I put into
     it.)  The idea here is that few people register for big,
     expensive shareware packages, especially ones which offer
     little else besides peace of mind as a reward to
     registration, which means I would get little feedback as far
     as what needs to be added.  I WANT FEEDBACK!

     Finally, to register, just print out the file
     "REGISTER.$15", fill out the information (especially *how
     you want to be notified of upgrades*!), fill out the
     questionnaire if you want, and send it (and a check or money
     order for the price of registration) to:

               Tom Dibble
               WPI Box 2466
               Worcester, MA  01609-2280

     This address will be good until the summer of 1995.

     Please feel free to add any comments you can about the
     program, especially suggestions for improvements in the
     interfaces, etc.  Also feel free to comment on this
     marketing strategy, the price, and/or similar programs.

     (A quick note on "similar programs":  Before uploading this
     program to the InterNet, I downloaded a few other graphing
     programs to see how Graph-Me! stood in relation.  As far as
     I could tell, very few other programs actually generated
     three-dimensional graphs, and of the ones which did, they
     were usually just demos for store-bought programs, the
     actual price of which hovered between $200 and $350.  I
     found one which almost sounded like it might be similar for
     $25, but I couldn't get it to work -- the command language
     was too confusing for the amount of time I had to play with
     it.  I would really appreciate it if anyone knows of any
     other program which does anything even *similar* that you
     tell me!)

STARTING UP:
     First, Graph-Me! is a relative hog for memory.  I know for a
     fact that it will *not* run in much less than 350Kb
     conventional memory.  So, before you start Graph-Me!, type
     'mem' to make sure you have enough memory to start out with.
     (Graph-Me! may be unkind if you run out of memory ... call
     it a bug ...)

     Once Graph-Me! is started, it may flash up a warning to your
     screen concerning GRAPHICS.COM, the DOS Print-Screen
     handler.  If you are running a replacement for GRAPHICS.COM
     (for instance, one which handles higher resolutions or
     colors specific to your printer), or simply do not want to
     print any of the graphs you generate out, ignore this
     message.  You may want to start Graph-Me! with the /NOGRAPH
     switch in the future.

     After that screen (press any key to clear it) is the
     copyright screen, which displays the name of the program,
     the author, the version, and the copyright date of
     Graph-Me!.  Again, press any key to clear this screen.
     The final initial screen (really!) is the video-mode
     selection screen.  Simply hit the numbers which best
     describe your system, or hit 'd' for auto-detect (advised,
     as setting video for a card which does not match your own
     may hang the program ... :-< ).  This setting may be changed
     at any time through the text interface, so don't sweat over
     it.

USAGE:
     Once Graph-Me! has started up, a simple point-and-click
     interface will appear on the screen.  It is divided into
     four sections: Plot Data, Options, Screen Data, and Formula.

     The Plot Data section holds the basic information about the
     plot: the ranges it covers, and the vertical and base
     rotations it has undergone.

     The Options section holds the zoom buttons and three other
     buttons, which will each bring up dialogue boxes.

     The Screen Data section holds information pertaining to the
     screen, such as the number of screen pixels between graph
     calculations, the video mode, and the screen resolution.  It
     also holds a few miscellaneous tidbits of data which
     probably should have been put elsewhere: the current
     graphing mode, the plotting directions, and the distance
     between sample planes.

     The Formula section holds the Dependant/Independent Variable
     information, the formula itself, and the "GRAPH-ME" button.

     The specific operation of each of these sections is detailed
     below.

     The text interface itself is by nature simple to use,
     especially if you have a mouse (and the driver is loaded
     into memory).  Simply move the highlighter bar to the field
     you wish to change by pressing <Tab> and <Shift>-<Tab>, then
     activate it by pressing <Space> or <Enter>.  Or, with the
     mouse, simply click on the field you wish to alter.  For
     instance, to enter a formula, press <Shift-Tab> (to cycle
     backwards through the fields) twice, highlighting the long
     formula bar at the bottom of the screen, then hit <Enter> to
     activate the input box.  Or, alternatively, simply click
     anywhere just above the "GRAPH-ME" button to select and
     activate the input box.

     Once you have entered a formula and defined the ranges (if
     you do not wish to stick with the defaults), activate the
     "GRAPH-ME" button.  The screen will clear, and three axis
     will appear, dead center on the screen.  Now the

          Arrow Keys:
               Rotate the graph in the direction indicated by the
               arrow key.
          Num-Lock + 'Arrow Keys': (numeric keypad)
               Shift the graph in the direction indicated.
          Page-Up:
               Zoom in.
          Ctrl-Page-Up:
               Less dramatic zoom-in
          Page-Down:
               Zoom out.
          Ctrl-Page-Down:
               Less dramatic zoom-out

     The Visual Interface also contains keystrokes with no
     command-line equivalent:
          '-':
               Decrease the Variable 1 Accuracy of the graph by
               one pixel.
          '+':
               Increase the Variable 1 Accuracy of the graph by
               one pixel.
          '\':
               Return Accuracy to one pixel.

          '-':
               Decrease the Variable 2 Accuracy of the graph by
               one pixel.
          '+':
               Increase the Variable 2 Accuracy of the graph by
               one pixel.

          '<':
               Decrease the sampling distance of variable 1.
          ',':
               Decrease the sampling distance of variable 2.
          '>':
               Increase the sampling distance of variable 1.
          '.':
               Increase the sampling distance of variable 2.
          '5', Home:
               Return system to start-up default settings.

          'Print-Screen':
               Currently the only way to obtain hard copy of the
               graph you produce.  The next full version should
               contain a GIF-encoder, as well as (perhaps) a
               proprietary format.  Also available (and
               recommended) to obtain hard-copy are numerous
               screen-grabbers, available (most likely) at the
               same site from which you obtained this.

PLOT DATA:
     The Plot Data section contains either four or five
     adjustable sections:  the '<=X=>' ... sections, and the two
     ROTATION specifiers.  To adjust the latter (the minimum and
     maximum values calculated), activate the appropriate
     selection bar.  A box will pop up asking you if you want to
     edit the mi(n)imum or ma(x)imum values; press the indicated
     letter or click on the option you choose.  An input-box will
     pop up, with which you can edit the values.  Operation of
     the input box is described below.

     The rotation angles are conceptually easier to understand
     from the graphical interface, so that is where I'll start in
     explaining them.  Set a formula in the Formula section, and
     select GRAPH-ME.  The graphics mode will come up.  Pressing
     the horizontal arrow keys (the left and right arrows), the
     graph spins in a certain way.  To be exact, the 'x' and 'y'
     axis are rotating about the 'z' axis.  This is called Base
     Rotation.  Pressing the vertical arrow keys causes the whole
     thing to tilt forward or backward.  This is Vertical
     Rotation.  Note that the Base Rotation is always taken
     before the Vertical Rotation.

     This understood, return to the text interface by pressing
     <Esc>.  The values under ROTATION: may have changed.  You
     may edit these directly to obtain an exact angle of view,
     but it is recommended that you rely on the graphical
     operation, as that is much simpler.  Note that the angles
     are in Radians.  (whatever * PI).  2*pi is a full rotation.

OPTIONS:
     The Options section of the screen holds five controls: the
     zoom controls, the "Extended Options" button, the "Mouse
     Control" button, and the "Help" button.

     The zoom controls act on the graph exactly as if you were in
     graphics mode and pressed Page-Up / Page-Down.  They zoom in
     / out by a factor of two.

     The Extended Options button brings up a new box with options
     in it, which is described later.

     The Mouse Control Button brings up a simple dialogue for
     controlling the mouse.  The controls are exactly as they
     look; to make your mouse move faster horizontally, click on
     the upper "Faster" bar.  To test any settings you have made,
     click "Test Settings".  To reset either direction, click on
     the reset button above the adjustments bar.  When you are
     done click on "Save and Leave".

     The Help button contains a few terse, on-line help screens.
     They are not meant as a substitute to the manuals, and so a
     manual-viewing option is included (of course, only if there
     is enough memory!).

STATUS:
     The Status section may contain between three and five input
     sections.  The five possible are: Mode (the graphing mode),
     Plotting Directions, Sampling Distance, Video Mode, and
     Accuracy.

     The Mode is adjusted by clicking on the MODE: bar and then
     selecting from amongst the available (5) modes.

     Plotting Directions tells which way(s) you want Graph-Me! to
     sample.  If this is "X-Only", then only lines which lie
     parallel to the 'x' axis will be drawn.  "Both" means that
     it will graph in both Independent Variable directions.

     Sampling Distance is the distance between mesh-lines.  The
     'x:' portion lists the distance between lines which *cross*
     the 'x' axis, etc.

     Video Mode adjusts the video mode, just like you did when
     you first started Graph-Me!.

     Accuracy defines how many pixels lie between successive
     calculations.  The default is one (the minimum) for lines
     (x,y,z,r) and pi/24 for angles.

FORMULA:
     The Formula section contains three selections: the Dependant
     Variable Selector, the Formula Bar, and the GRAPH-ME button.

     The Dependant Variable selector is your tool for deciding
     how your formula will be input.  Basically, every graph has
     one dependant variable and up to two independent variables.
     For instance, in 'Box' mode, 'Z' may be the dependant
     variable, and 'x' and 'y' the independent variables.  By
     activating the DVS, you can choose between the current
     solution and the two other possibilities.  The DVS also
     gives you important information you will need when you try
     to adjust the accuracies of your graph: the First
     Independent Variable (IV1) is listed first, and IV2 is
     listed second.  When the formula is graphed, the first pass
     is made holding IV1 constant at several values (so the
     accuracy is adjusted using the '/' and '*' buttons), and the
     second pass is made holding IV2 constant at several values
     ('-' and '+').

     The Formula Bar activates an input box for your formula.
     Generation of that formula is listed elsewhere in this
     document (the next section).

     Finally, the GRAPH-ME button sets the grapher into motion,
     clearing the screen and activating graphics mode.


THE FORMULA:
     As far as it can be done, you type your equation into
     Graph-Me! just as you would write it down on a sheet of
     paper.  For your own peace of mind, you might want to place
     parentheses strategically throughout, but, for the most
     part, if they were not needed when you wrote your formula
     down on paper, they aren't needed when you put your equation
     into Graph-Me!.  Also, spaces sometimes make it easier for
     you to decipher your own equations, and as such are highly
     advised.  Spaces will not slow down Graph-Me! at all, though
     extensive use of parentheses might cause an unnoticeable
     increase in the amount of time it takes to calculate a
     graph.

     Another feature of the formula input technique is the
     auto-multiply feature.  Simply put, things like '4x' are, as
     they should be, entirely equivalent to '4*x'.  This leads to
     easier input as well as a more 'natural' feel which so many
     calculators and such lack.

     The operators are listed below, under 'LANGUAGE DEFINITION'.
     They perform the operation indicated to their right.  A
     discussion of first-, second- and third- level operators is
     in the file LEVELS.DOC, which should have been included.


     A quick note on the alternate input sequence of absolute
     value signs -- '|'.  These can be a bit tricky.  For any
     given level of parentheses, the first symbol encountered is
     translated as 'abs' and '('.  The second symbol on that
     level is then translated as ')'.  This works quite well most
     of the time.  However, a notable exception is the following
     line:
               | ln | r | |
     If I saw that on a written page, I would translate it as
               | (ln|r|) |
     but, since the ln sign does not decrease the parentheses
     level, Graph-Me! translates this line as
               |(ln)| * |(r)|
     which, of course, makes no sense when it actually goes to
     calculate out.  The moral is:  be very careful when using
     the alternate input sequence for absolute value, or simply
     use the 'normal' input sequence of 'abs(whatever)'.
          ( '| ln(|r|) |' works )



WHY GRAPH-ME! ?
     I envision Graph-Me! as a tool for visualizing complex
     formulas in three dimensions.  Given the proliferation of
     hand-held 'graphics' calculators in recent years, there
     should be a need for three-dimensional graphs as well.  (I
     bought a Casio 'Graphics' two years ago, used it for a
     while, then retired it to the bottom of my desk drawer
     because it couldn't handle the things I wanted it to
     handle -- namely, three dimensions.)  Also, it's a kinda
     neat toy.


LANGUAGE DEFINITION:
     Basic Operators (First-Level):
          (,[  open parenthesis
          ),]  close parenthesis
          +    plus
          -    minus
          \0   EOL

     Second-Level Operators:
          *    times
          /    divided by
          ^    to power of ...
          %    modulus

     Third-Level Operators:
          sin,si         sine
          cos            cosine
          tan,ta         tangent
          sec,se         secant
          csc            cosecant
          cot            cotangent
          asin,asi       arcsine
          acos           arccosine
          atan,ata       arctangent
          asec,ase       arcsecant
          acsc           arccosecant
          acot           arccotangent
          abs, ab, |     abs. value ('|' encloses expression)
          ln             natural log
          e^,exp         'e' to the ...
          log,lo         log base ten
          gt             least integer greater than
          lt             greatest integer less than


     Variables:
          x
          y
          z
          th, theta
          ph,phi
          r,rho,rh

     Defined Constants:
          pi
          e



ACKNOWLEDGEMENTS:
     Graph-Me! was programmed and compiled on a 386SX-16 using
     Borland Intl.'s Turbo C ver 2.0.  Video support is courtesy
     of the BGI interface included with that package.

     The recursive-descent parser grew out of an example in
     _Advanced_C_Programming_, a book by Steven Oualline and the
     Peter Norton Programming Group.  It has been greatly
     modified and totally re-structured, but the basic idea I owe
     to that book.



 *   COPYRIGHT NOTICE:
 *        This program, Graph-Me!, and all supporting
 *        documentation, is hereby copyrighted by Tom
 *        Dibble for use on personal computers, home
 *        and/or business.  All other use is strictly
 *        prohibited except by express written permission
 *        of the author, Tom Dibble.

 *   VERSION NOTES:
 *
 *        1.0  At last!  A production version!  Expanded the new
 *             interface to work in all modes, connected the
 *             help system and Extended Options box.  Fixed a few
 *             minor bugs in the interface and in controls.  Most
 *             of all, though, I got everything to finally work
 *             well together.  Graph-Me! 1.0 Released on Dec 9,
 *             1992.
 *
 *        0.97 Finally slapped on the interface.  Reworked
 *             controls to be a bit more intuitive.  Various
 *             improvements relating directly to the new
 *             interface.
 *
 *        0.96 Totally new recursive descent parser, which
 *             works many times better than the old one (ie,
 *             3-2+4 comes out as 5 rather than -3).
 *             Calculator Mode now allowed.  ('#Calc')
 *
 *        0.95 Fixed spherical plotting so that it now goes
 *             in the right direction, and made MaxPhi = PI
 *             by default.  Also, '/' and '*' change accuracy
 *             as well as spacing.  'gt' and 'lt' algorithms
 *             added, as brethren to modulus.
 *             Added tick-marks to graph.
 *             Ctrl-( PgUp || PgDwn ) perform same as Pg-Up /
 *             Pg-Dwn, but in a smaller increment.
 *
 *        0.94 Greatly improved the calc() algorithms.  Sin
 *             now works properly (sin(2*3)*x now is graphed
 *             as "(sin(2*3))*x").  Modulus ('%') was added,
 *             in somewhat standard form (legal for all types
 *             of operators, integer and otherwise).
 *
 *        0.93 Second set of speed-up put in.  Now the 'eqline'
 *             string is fully expanded into an array of
 *             tokens by the pre_calc() function.  Timed
 *             savings of about 1-2% on simple graphs (sinx)
 *
 *        0.92 First set of speed-up code installed.  The
 *             input string is parsed and translated to a far
 *             more orderly line by pre_calc(), and all
 *             input numbers are put into the flnum[] array.
 *             Timed savings of .1% on sinx and 10% on
 *             '5.0e0*sin(4*x)'
 *
 *        0.91 First 'version'-ed program.  Far from ready
 *             to be put out for mass consumption.  It is
 *             slow, and lacks any interface beyond a very
 *             simple and quite dumb CLI.  On the interface
 *             side, however, we *do* have a strong line-
 *             editor, and a history buffer.  (COOL!)
 *
 *        Pre-Version 0.91:
 *             You don't want to know.
 *


 *   The Author:
 *
 *        College Address:
 *             Tom Dibble
 *             W.P.I. box 2466
 *             Worcester, MA  01609-2280
 *
 *        Alternate Home Address:  (Summer, holidays)
 *             Tom Dibble
 *             8087 Willow Glen Ct
 *             Citrus Heights, CA  95610
 *
 *        InterNet Address:
 *             [e-mail]